[Cosmos] N-Region Synchronous Commit: Propagate SDK Supported Capabilities to BE With Data Plane and Barrier Requests#48965
Merged
kundadebdatta merged 10 commits intomainfrom Apr 29, 2026
Conversation
- Add '// Visible for testing' comment on package-private constants - Use 1 << 0 for PARTITION_MERGE for consistency with other bit flags - Add doc comment on IGNORE_UNKNOWN_RNTBD_TOKENS explaining its purpose Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Enables Cosmos DB N-Region Synchronous Commit negotiation by ensuring the SDK-supported capabilities header is propagated on barrier request paths, and by expanding/validating the SDK capability bitmask definitions.
Changes:
- Add additional SDK capability flags and include
IGNORE_UNKNOWN_RNTBD_TOKENSin the default supported capabilities value. - Attach
x-ms-cosmos-sdk-supportedcapabilitiesto barrier requests. - Add/extend unit tests to validate capability bits and barrier header propagation; update changelog.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/directconnectivity/BarrierRequestHelper.java | Adds SDK supported capabilities header to barrier requests. |
| sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/HttpConstants.java | Expands capability flags and updates default supported capabilities composition. |
| sdk/cosmos/azure-cosmos/CHANGELOG.md | Documents the new capability flag and barrier propagation. |
| sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/implementation/directconnectivity/BarrierRequestHelperTest.java | Verifies barrier requests include the capabilities header. |
| sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/implementation/SDKSupportedCapabilitiesTest.java | Adds tests validating capability bit values and composed supported capabilities. |
FabianMeiswinkel
requested changes
Apr 29, 2026
Member
FabianMeiswinkel
left a comment
FabianMeiswinkel
left a comment
There was a problem hiding this comment.
I think THROUGHPUT_BUCKETING should also be enabled? Or what exactly is gated behind this flag?
kundadebdatta
deleted the
users/kundadebdatta/add_sdk_supported_capabilities
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Background
This PR enables the N-Region Synchronous Commit feature by ensuring the Cosmos DB Java SDK advertises its supported capabilities to the backend on all request paths — including barrier requests, which were previously missing this header.
Motivation
The N-Region Synchronous Commit flow requires the backend (BE) to return new RNTBD response tokens (e.g.,
GlobalNRegionCommittedGLSN) that older SDK versions would not recognize. The SDK must signal via thex-ms-cosmos-sdk-supportedcapabilitiesheader that it can safely ignore unrecognized RNTBD tokens. Without this header on barrier requests, the BE cannot return the N-Region commit LSN during barrier operations.Changes
1.
HttpConstants.java— Expanded SDK Supported Capabilities (+14 / −5)THROUGHPUT_BUCKETING(1 << 2= 4)IGNORE_UNKNOWN_RNTBD_TOKENS(1 << 3= 8) — signals that the SDK can handle unrecognized RNTBD transport tokensCHANGE_FEED_TOKEN_WITH_GCN(1 << 4= 16)SUPPORTED_CAPABILITIESfromPARTITION_MERGE | CHANGE_FEED_WITH_START_TIME_POST_MERGE(value3) toPARTITION_MERGE | CHANGE_FEED_WITH_START_TIME_POST_MERGE | IGNORE_UNKNOWN_RNTBD_TOKENS(value11)privateto package-private (static final) to enable unit test accessIGNORE_UNKNOWN_RNTBD_TOKENS1 << Nnotation for all bit-shift definitions2.
BarrierRequestHelper.java— Attach Capabilities Header to Barrier Requests (+3 / −0)SDK_SUPPORTED_CAPABILITIESheader with the value ofSDKSupportedCapabilities.SUPPORTED_CAPABILITIESto barrier requests created byBarrierRequestHelper.createAsync()X_DATE,TARGET_LSN,TARGET_GLOBAL_COMMITTED_LSN,AUTHORIZATION,PARTITION_KEY, andCOLLECTION_RIDheaders — now they also advertise the SDK's supported capabilities3.
BarrierRequestHelperTest.java— Test Coverage for Barrier Requests (+2 / −0)barrierDocumentReadNameBasedRequesttest to verify theSDK_SUPPORTED_CAPABILITIESheader is present on barrier requests with the expected value4.
SDKSupportedCapabilitiesTest.java— New Unit Test File (+74 / −0)capabilityBitValues: Validates each individual capability flag has the correct numeric value (0, 1, 2, 4, 8, 16)capabilityBitsDoNotOverlap: Ensures no two capability flags share the same bit positionsupportedCapabilitiesIncludesExpectedFlags: Verifies the combinedSUPPORTED_CAPABILITIESstring equals the expected bitwise OR ofPARTITION_MERGE | CHANGE_FEED_WITH_START_TIME_POST_MERGE | IGNORE_UNKNOWN_RNTBD_TOKENSsupportedCapabilitiesNone: ConfirmsSUPPORTED_CAPABILITIES_NONEequals"0"supportedCapabilitiesNumericValue: AssertsSUPPORTED_CAPABILITIESis"11"supportedCapabilitiesContainsIgnoreUnknownRntbdTokens: Bitwise checks thatIGNORE_UNKNOWN_RNTBD_TOKENSis set in the final capabilities value5.
CHANGELOG.md— Release Notes Entry (+1 / −0)4.80.0-beta.1> Features Added documenting the new capability flag and barrier request propagationFiles Changed Summary
sdk/cosmos/azure-cosmos/src/main/java/.../HttpConstants.javaIGNORE_UNKNOWN_RNTBD_TOKENSin default capabilitiessdk/cosmos/azure-cosmos/src/main/java/.../BarrierRequestHelper.javaSDK_SUPPORTED_CAPABILITIESheader to barrier requestssdk/cosmos/azure-cosmos-tests/.../BarrierRequestHelperTest.javasdk/cosmos/azure-cosmos-tests/.../SDKSupportedCapabilitiesTest.javasdk/cosmos/azure-cosmos/CHANGELOG.mdHow to Verify
SDKSupportedCapabilitiesTest(group:unit) to validate capability bit definitions and the composed valueBarrierRequestHelperTest(group:direct) to confirm theSDK_SUPPORTED_CAPABILITIESheader is present on barrier requestsx-ms-cosmos-sdk-supportedcapabilitiesheader value is"11"on both data-plane and barrier requestsAll SDK Contribution checklist:
General Guidelines and Best Practices
Testing Guidelines